Version: 24.05

Digital Twins

Industry Core kit banner

Industry Core uses digital twins to make a company's data available to other Catena-X partners. Basics about digital twins with which you should be familiar to understand this section are described in the Digital Twin KIT.

Register Digital Twins

In Industry Core, different types of parts, e. g. serialized parts, batches, JIS parts or catalog part, are registered in a company's DTR as digital twins.

Regulatory Compliance and Security

To enforce a strict need-to-know principle (and to prevent data from being exposed to non-authorized partners in the Catena-X network), the visibility of digital twins and the content of the attribute specificAssetIds of digital twins must be restricted to authorized partners only. The actual implemenetation depends on the DTR product used by the Catena-X partner. More details can be found in the Digital Twin KIT.

Unique ID for Parts

In the Industry Core, a Unique ID uniquely identifies a particular real-world asset. Currently, these are: serialized parts (including vehicles), batches, JIS parts (Just-in-Sequence) and also catalog parts.

A Unique ID is a URN and has the following format: urn:uuid:<UUIDv4>, i.e., the NID is "uuid" and the NSS is a UUID Version 4 (as described here: https://en.wikipedia.org/wiki/Universally_unique_identifier).

The Unique ID mus be created by the manufacturer of the part. At the latest, it must be created when the digital twin for this part is created as the Unique ID is part of the digital twin information.

Unique IDs are used in several places in the Industry Core, e.g., as globalAssetId for digital twins or as catenaXId in aspect models.

Conventions for Creating Digital Twins

The following general conventions apply for all digital twins:

id: The AAS ID must be a UUIDv4 in URN format: urn:uuid:<UUIDv4>;
globalAssetId: the Unique ID of the real-world part for which a digital twin is created.

⚠️ AAS ID and Unique ID are different identifiers, although they share the same format (UUID) and therefore look the same. A Unique ID identifies real-world assets, whereas a AAS ID identifies a digital twin of such an asset. Do not use the same value for Unique ID and AAS ID for a digital twin.

✋ Unique ID Push: Once a digital twin was registered (initially created), optionally a Unique ID Push notification can be send from the manufacturer (creator of the digital twin) to the customer of the part to inform it that a new digital twin is available.

Property specificAssetIds

Specific asset IDs are used to identify digital twins when looking up or searching for these digital twins. This is a required step by a customer of a part to connect the digital twins of their parts with the digital twins of the suppliers' child parts. To a customer, only the information printed on a real-world part is available and can be used for the lookup. Mandatory specific asset IDs ensure that at least this information is available for the digital twin.

The following conventions for specific asset IDs apply to all digital twins:

Key	Availability	Description	Type
manufacturerId	Mandatory	The Business Partner Number (BPNL) of the manufacturer of the part.	BPNL
manufacturerPartId	Mandatory	The ID of the type/catalog part from the manufacturer.	String
customerPartId	Optional	The ID of the type/catalog part from the customer. The main reason why this propertiy is optional is that it cannot be guaranteed that every manufacturer knows the customerPartId for their parts. In case the manufacturer knows the customer and the corresponding CustomerPartID of its part though, it is required to add this information for easier lookup and to enable further processes.	String
digitalTwinType	Mandatory	The type of the digital twin: "PartInstance" for serialized parts, batches, and JIS parts "PartType" for catalog parts digitalTwinType was added to allow data consumers to search for all digital twins of a particular type, e.g, only for catalog parts by using `digitalTwinType="PartType"` as filter. Without this filter, a search for a particular manufacturer part ID would not only return the digital twin of the catalog part, but also all digital twins of instances of this catalog part, i.e., of the corresponding serial parts.	String

For serialized parts, additionally the following conventions apply:

Key	Availability	Description	Type
partInstanceId	Mandatory	The serial number of the part from the manufacturer.	String
intrinsicId	Mandatory	This the unified technical key for searching a digital twin of a part. In this case the partInstanceId is used as the intrinsicId.	String
van	Optional	Only for vehicles: The pseudonymized vehicle identification number (VIN) of the vehicle.	String

For batches, additionally the following conventions apply:

Key	Availability	Description	Type
batchId	Mandatory	The number of the batch from the manufacturer.	String
intrinsicId	Mandatory	This the unified technical key for searching a digital twin of a batch. In this case the batchId is used as the intrinsicId.	String

For just-in-sequence (JIS) parts, additionally the following conventions apply:

Key	Availability	Description	Type
parentOrderNumber	Optional	A number identifying the just-in-sequence- part's destination parent part. The parent part is typically known upfront to the supplier for just-in-sequence parts.	String
jisNumber	Mandatory	A number that is used to identify the call-off that can be assumed unique within the specific just-in-sequence process. This is typically not the sequence number, but the call-off number.	String
jisCallDate	Optional	The date of the just-in-sequence call-off as stated on the call-off document itself. The value must be compliant to ISO 8601: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ss` or `YYYY-MM-DDThh:mm:ss±hh:mm`	Date
intrinsicId	Mandatory	This the unified technical key for searching a digital twin of a just-in-sequence (JIS) part. In this case a composition of `jisNumber`, `parentOrderNumber` (if available), `jisCallDate` (if available) is used as the intrinsicId. This information is typically known upfront to the supplier `jisNumber`, `partOrderNumber` and `jisCallDate` for just-in-sequence parts.	String

✋ Lookup of Digital Twins The lookup for parts can use the customerPartId or the manufacturerPartId. Both, manufacturer and customer must agree upon what part ID will be used for the lookup. Otherwise, when the customer would use the customerPartId for the lookup, but the manufacturer would only provide the manufacturerPartId in its digital twins, the lookup would fail every time. This is decision that a customer must agree upon with each of their suppliers individually. In order to provide a standardised way to look-up digital twins, the specificAssetIDs are extended by a unified technical key, the intrinsicId. This ensures a correct semantic filling of all other existing attributes in the specificAssetIDs, as the partInstanceId was previously used as an overarching search field, which resulted in the partInstanceId being filled with a batch number for a batch, for example. Nevertheless, a search for digital twins can still be used via the corresponding the primary fields from a business point of view, such as partInstanceId or batchId.

standardised identification of a digital twin based on technical key attributes Correct semantic filling of all existing fields in the specificAssetIDs (e.g. filling of the partInstanceIDs attribute for JisParts)

Submodel Descriptors

To enforce a strict need-to-know (and prevent data from being exposed to non-authorized parties), the visibility of entries in the attribute specificAssetIds must be protected, i.e.,their visibility must be restricted to authorized parties only. For that, the attribute externalSubjectId must be used. Detailed information about this can be found in the Digital Twin KIT.

Submodel Descriptors

Submodel descriptors must be compliant with the guildeines from the Digital Twin KIT as well as the following additional conventions:

id: The submodel ID must be a UUIDv4 in URN format: "urn:uuid:<UUIDv4>";
idShort: the name of the aspect model in camel case, e.g. for aspect SerialPart: "serialPart".

The actual access information for the Connector is part of the endpoint attribute in the submodel descriptor.

{
    "interface": "SUBMODEL-3.0",
    "protocolInformation": {
        "href": "https://connector.data.plane/{publicContextPath}/{providerPath}/submodel",
        "endpointProtocol": "HTTP",
        "endpointProtocolVersion": ["1.1"],
        "subprotocol": "DSP",
        "subprotocolBody": "dspEndpoint=https://connector.control.plane/{catalogPath};id=123",
        "subprotocolBodyEncoding": "plain",
        "securityAttributes": [
          { "type": "NONE", "key": "NONE", "value": "NONE" }
        ]
    }
}

The following conventions apply for the endpoint:

interface, endpointProtocol, endpointProtocolVersion, subprotocol, subprotocolBodyEncoding, and securityAttributes are set as defined in the CX-0002 standard.
href: The endpoint address for the logical operation GetSubmodel that is invoked by a data consumer to get the submodel. It must have the following format:
- https://connector.data.plane/{publicContextPath}: Address of the Connector data plane that is providing the submodel. {publicContextPath} is configured in the Connector settings and defaults to /api/public.
- {providerPath}: This string is forwarded to the backend data service by the Connector data plane. Together with the Connector asset information (see below) it must contain all information for the backend data service to return the requested submodel. The actual path depends on the type of backend data service that the data provider uses to handle the request. More details follow below.
- submodel: This submodel string is also forwarded to the backend data service. As AAS Profile SSP-003 of the Submodel Service Specification is mandatory for this release, href must have the suffix /submodel representing the invokation of the GetSubmodel operation.
subprotocolBody: a semicolon-separated list of parameters used to negotiate the required contract agreement.
- dspEndpoint: Base URL of the catalog service endpoint of a DSP Connector. The consumer Connector can use:
  - catalog/request to fetch the full catalog and search for the dataset in the catalog or
  - catalog/datasets/{id} to only fetch offers for the dataset with a particular dataset ID.
- id: The ID of the Connector asset for which a contract negotiation should be intiated. This ID is also called dataset ID as it is stored as https://www.w3.org/ns/dcat/dataset.@id in a catalog entry. This ID must be set by the data provider when creating the asset. Do not confuse this Connector asset ID (dataset ID) with other IDs that might be defined additionally for a Connector asset, e.g., https://w3id.org/edc/v0.0.1/ns/id (often refered to as edc:id).

With this approach, the Connector asset structure must no longer follow the "one asset per submodel" rule (as in Release 3.1 and before), but gives data providers more flexibility how to create assets for their digital twins and submodels based on how they use {providerPath}.

Option 1: Same Connector Asset Structure as in Release 3.1

Submodels of digital twins are registered in the Connector the same way as for release 3.1: One asset is created for every submodel of a digital twin.

href must have the following format: https://connector.data.plane/{publicContextPath}/submodel
subprotocolBody must have the following format: dspEndpoint=https://connector.control.plane/{catalogPath};id={datasetId} with {datasetId} the ID of the Connector asset for the submodel.

Here's an example how such a submodel descriptor could look like:

"submodelDescriptors": [
  {
    "idShort": "serialPart",
    "id": "urn:uuid:7effd7f4-6353-4401-9547-c54b420a22a0",
    "semanticId": {
      "type": "ExternalReference",
      "keys": [
        {
          "type": "GlobalReference",
          "value": "urn:samm:io.catenax.serial_part:1.0.1#SerialPart"
        }
      ]
    },
    "endpoints": [
      {
        "interface": "SUBMODEL-3.0",
        "protocolInformation": {
          "href": "https://connector.data.plane/api/public/submodel",
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion": ["1.1"],
          "subprotocol": "DSP",
          "subprotocolBody": "dspEndpoint=https://connector.control.plane/api/v1/dsp;id=urn:uuid:7effd7f4-6353-4401-9547-c54b420a22a0",
          "subprotocolBodyEncoding": "plain",
          "securityAttributes": [
            { "type": "NONE", "key": "NONE", "value": "NONE" }
          ]
        }
      }
    ]
  }
]

In this example, the {providerPath} part in the href is empty, as the Connector asset referenced in subprotocolBody directly points to a service returning the correct submodel (set up correctly with its dataAddress in the data provider's Connector).

Option 2: Connector Asset Structure on Catalog Part Level

A data provider can link several submodel endpoints to the same Connector asset (referenced by its ID). This allows to create only one asset (per aspect model) for a catalog part and link all submodels (of the same aspect model) for serialized parts of the catalog part to the same asset. The data provider would still need to create separate assets per aspect model as in most cases different usage policies are used for aspect models.

If a data provider no longer creates assets on the level of submodels, the Connector can no longer authorize a request on a submodel-level. For example: If assets are created per catalog part, the Connector can only authorize if the requestor is allowed to see parts of these type in general; if the requestor is allowed to see a actual serialized part, must be authorized by the backend data service executing the request.

Here's an example how such a submodel descriptor could look like:

"submodelDescriptors": [
  {
    "idShort": "serialPart",
    "id": "urn:uuid:7effd7f4-6353-4401-9547-c54b420a22a0",
    "semanticId": {
      "type": "ExternalReference",
      "keys": [
        {
          "type": "GlobalReference",
          "value": "urn:samm:io.catenax.serial_part:1.0.1#SerialPart"
        }
      ]
    },
    "endpoints": [
      {
        "interface": "SUBMODEL-3.0",
        "protocolInformation": {
          "href": "https://connector.data.plane/api/public/urn%3Auuid%3A7effd7f4-6353-4401-9547-c54b420a22a0/submodel",
          "endpointProtocol": "HTTP",
          "endpointProtocolVersion": ["1.1"],
          "subprotocol": "DSP",
          "subprotocolBody": "dspEndpoint=https://connector.control.plane/api/v1/dsp;id=urn:uuid:1475f313-0a83-4e2b-b705-a100eebcb7d7",
          "subprotocolBodyEncoding": "plain",
          "securityAttributes": [
            { "type": "NONE", "key": "NONE", "value": "NONE" }
          ]
        }
      }
    ]
  }
]

The the {providerPath} part of the href property contains the information for the backend data service which digital twin's submodel to return while the asset ID is used for several endpoints. The path part here is just an example as it depends on the type of backend data service the data provider uses.

The above options are only two examples how a submodel's endpoint can be created. As long as it's compliant with the above conventions (including CX-0002) a data provider can also use any other asset structure.

Data Consumption with AAS Submodel Descriptor Endpoints

A data consumer must first identify the correct submodel descriptor for a Catena-X data transfer. For Catena-X submodel descriptors, the subprotocol attribute must have the value "DSP". Then, the data consumer must use the information in the subprotocolBody to perform a contract negotiation for the asset referenced by id with the Connector of the data provider specified by dspEndpoint and afterwards initiate the data transfer.

Further information about the data transfer of submodels can be found in the Digital Twin KIT.

Lookup in the Digital Twin Registry

For a data provider, there are currently the following steps where they have to lookup digital twins of other partners in the Catena-X network.

The data provider must use the local IDs for a serialized part or batch (manufacturer, part number, serial or batch number) and for a just-in-sequence part (manufacturer, parentOrderNumber, jisNumber, jisCallDate) to lookup the AAS ID of the digital twin of this serialized part, batch or just-in-sequence part. The AAS descriptor with this ID contains the Unique ID of the serialized part, batch or just-in-sequence (as globalAssetId) that is used to create SingleLevelBomAsBuilt submodel.
The data provider must use the local IDs for a catalog part (manufacturer, part number) to lookup the AAS ID of the digital twin of this catalog part. The AAS descriptor with this ID contains the Unique ID of the catalog part (as globalAssetId) that is used to create the SingleLevelBoMAsPlanned submodel.

For a data consumer, there are currently the following steps where they have to lookup digital twins of other partners in the Catena-X network.

The data consumer in the Traceability use case in most cases will use the Unique ID of a part to lookup the digital twin (more precisely, its AAS ID) of this part.
The data consumer from another use case (e.g., Circular Economy), might either use the Unique ID of a part (if known) or the local IDs of a part to lookup the part's digital twin (AAS ID) depending on what is available in the use case.

Lookup up a Digital Twin with Local IDs

The local IDs of a serialized part (manufacturer, part number, serial number) are stored as specific asset IDs in the AAS descriptor of the digital twin. From the Digital Twin Registry API, the following function can be used for this lookup GET /lookup/shells.

All Asset identifier key-value-pairs used as parameter to this lookup function are passed to the API separately via the parameter assetIds in Base64 format. An example query would look like this: /lookup/shells?assetIds=ewogICJuYW1lIjogIm1hbnVmYWN0dXJlcklkIiwKICAidmFsdWUiOiAiQlBOTDc1ODg3ODc4NDlWUSIKfQ==&assetIds=ewogICJuYW1lIjogIm1hbnVmYWN0dXJlclBhcnRJZCIsCiAgInZhbHVlIjogIjk1NjU3MzYyLTgzIgp9&assetIds=ewogICJuYW1lIjogInBhcnRJbnN0YW5jZUlkIiwKICAidmFsdWUiOiAiTk8tNTc0ODY4NjM5NDI5NTUyNTM1NzY4NTI2Igp9

The assetIds value looks like this unencoded (but with additional spaces and linebreaks):

First assetIds parameter:

{
  "name": "manufacturerId",
  "value": "BPNL7588787849VQ"
}

Second assetIds parameter:

{
  "name": "manufacturerPartId",
  "value": "95657362-83"
}

Third assetIds parameter:

{
  "name": "partInstanceId",
  "value": "NO-574868639429552535768526"
}

The lookup (for serialized parts/batches as well as catalog parts) can use the customer or the manufacturer part ID (manufacturerPartId or manufacturerPartId).

For a digital twin, adding the customer part ID to the specific asset IDs is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part ID for their parts. But, if they know it, it is recommended to always add the customer part ID to the specifiAssetId property for easier lookup (by customers).
A customer that wants to do a lookup for a supplier's digital twin, must first decide what ID they want to use for the lookup. This depends on the information that is available to them.
- If the customer knows the manufacturer part id, they should use the manufacturer part ID for the lookup as the manufacturer part ID is guaranteed to be available in the digital twin (as the manufacturer part ID is a mandatory property).
- If the customer does not know the manufacturer part id, they must use the customer part ID (i.e., their own part id). In that case they must make sure that their suppliers register their digital twins with this information (as the customer part ID is optional) as part of the specific asset IDs. This is decision that a customer must agree upon with each of their suppliers individually.

As a result, the AAS ID of the digital twin with this local IDs is returned. The AAS ID can then be used to retrieve details about the digital twin, i.e. the digital twin's AAS descriptor including submodel descriptors.

Example result for looking up a digital twin with local IDs:

["urn:uuid:c227a880-b82b-40f7-846c-3942ddf26c29"]

Note that this query can return more than one AAS ID depending on the local IDs uniquely identifying a digital twin or not.

Currently, even if more than one digital twin is returned in a lookup, these digital twins should have different submodels assigned to them. These submodels should be disjunct and not overlap. This means that you can use the submodel to filter out the correct digital twin.

If there are returned more than one digital twin with the same submodel (based on their semanticId), this is considered an error. Processing should be canceled and an error message should be reported.

The next section describes to modify the lookup to additionally restrict the results to digital twins with a specific submodel type based on it's semanticId.

Unique ID Push

Once the digital twin was created, optionally a Unique ID Push notification can be send by the manufacturer of the part to the customer of the serialized part of batch to inform the customer that information about a serialized part or batch is available as a digital twin. This is an optional process and both, the manufacturer of a part as well as the customer of the part must support Unique ID Push notifications.

For more information, see Unique ID Push Notifications

Query a Digital Twin Registry to find the digital twin for this built-in part

Querying digital twins is described in Lookup in the Digital Twin Registry
- Note that the query parameters differ depending on what type of digital twin is looked up.
  - Regardless of whether you want to search for serialised parts, batches or just-in-sequence (JIS) parts, you can currently use the intrinsicId as a standardised technical key to look up digital twins. You can find the corresponding filling of this attribute in the tables above, depending on which specification is involved.
  - However, if you already know the specification of the digital twin you are looking for before the look up, you can also carry out a search using the corresponding key attributes, like partInstanceId, batchId or a composition of jisNumber, parentOrderNumber (if available), jisCallDate (if available). The partInstanceId with search parameter value serial number should be used for serialised parts, the batchId with search parameter value batch number for batches and a composition of jisNumber, parentOrderNumber (if available), jisCallDate (if available) with their corresponding search parameter values for JIS parts.
- To understand why, take a look at how these digital twins are created, especially their specific asset IDs.
- The result of this query will be the AAS ID of the digital twin.
Use this AAS ID to get the AAS Descriptor including all Submodel Descriptors of this digital twin. The AAS Descriptor contains the Submodel Descriptor SerialPart or Batch (depending on the digital twin type).
Fetch the submodel SerialPart or Batch (depending on the digital twin type) from the Connector that is referenced in the corresponding Submodel Descriptor.
The submodel then contains the Unique ID of the built-in part in its catenaXId attribute.

These steps have to be repeated for all built-in parts by the manufacturer. After that, the manufacturer has all information to create the SingleLevelBomAsBuilt.

Publish Traceability Data Offers in the Connector

With the flexible approach described above, the actual asset structure for submodels in the Connector is no longer restricted by use case conventions and can be decided by the data provider.

Data Provider Tasks

Basically, as a data provider you have to do the following

Implement a Backend Data Service (BDS) for every asset that is provided via the Connector. It does not have to be a different BDS for each asset - you can use the same BDS for several assets (to be verified).
The BDS must support the Asset Administration Shell Profile SSP-003 of the Submodel Service Specification (see standard CX-0002 for more details).
The BDS must use the REST API data plan for data transmission.
The BDS must verify that it only returns data to the data consumer that is compliant to the asset and data offer for which data is queried and authorize the request accordingly.

Unique ID Push

Unique ID Push notifications provide the possibility to push specific information to a business partner in the value chain (one level up or one level down). This can help to provide faster information to reduce necessary information collection activities (connect-to-parent) or to provide information that is not available at all at the receiver side (connect-to-child).

The solution is based on notification assets in the EDC (which is the same approach that is used for quality incidents). The notification receiver creates a notification asset in the EDC and the notification sender sends his notifications to this notification asset. As this notification asset is a general EDC asset - as for all EDC assets - access policies, usage policies and contract definitions must be created.

✋ It is important to understand that the receiver creates EDC asset and policies, and thus, the sender of the Unique ID push notification must check during the EDC negotiation process if the conditions the receiver offers are acceptable for the sender.

Currently there are two types of Unique ID Push Notifications available: "Connect to Parent" and "Connect to Child".

Connect to Parent

Unique ID Push notifications of type "connect-to-parent" are a way for a manufacturer to notify a customer as soon as possible when a new digital twin for a part is available.

The sender of the notification is the supplier of a part item and the receiver of the notification is the customer of that part item. The Unique ID of that part is sent in the notification.

Connect to Child

Unique ID Push notifications of type "connect-to-child" are a way for a manufacturer to notify a supplier when the supplier's part has been used (or is to be used in the case of part type) in the assembly or production of the manufacturer's product. This will result in an update of the corresponding SingleLevelUsage aspect at the supplier side.

The sender of the notification is the customer of a part item or type and the receiver of the notification is the supplier of that part item or type. The Unique ID of that part, quantity and dates are sent in the notification.

Connect to Parent and Connect to Child notifications can be applied to Digital Twins for part instances and for part types.

Prerequisites and Constraints

In order to be able to push Unique ID(s) of part(s) to the correct partner, it is required that the sender pushing the Unique ID notification is aware of the BPN of the receiver of the notification or has enough data in its context to use BPDM functions to determine the BPN Number of the receiver.

For actively pushing Unique ID notifications, an EDC is required and the data provider needs to be enabled to execute the complete process including EDC communication and HTTP Push (i.e., HTTP POST) of the payload.

Secondly, EDCs are being used for the exchange and it is currently required to offer a HTTP POST API to receive the Unique ID notifications push at the receiver's side. This API needs to be registered in the EDC Catalog as a data offer and requires specific properties to be set to standardized values, as this allows discoverability. Details still tbd.

Unique ID Push Process Overview

Connect to Parent

How the actual process is triggered is application specific. It is recommended to trigger the push of Unique IDs towards the customer after the Goods Issue has been booked, since commonly at that point the serial numbers/batch numbers of the parts being delivered are fixed in the logistics process and shall be contained in delivery documents, EDI Messages and/or any internal representation of the received items (non-Catena-X communication).

The Unique ID push is initiated by the supplier (acting as sender) towards their customer (acting as receiver). Since the Unique ID of the asset (i.e., serial unit / batch) is unknown in the logistics process, the message needs to include local identifiers to be matched towards the information from the delivery documents and furthermore the internal data of the recipient's traceability solution.

Upon receipt of the message, the customer needs to match the local identifiers with its internal traceability records and attach each Unique ID to the respective data set. How this is done is depending on the customer's internal systems:

If there is an object for incoming deliveries, this event could be updated. Alternatively, if only production events are tracked, the data could be integrated at this point into the data provisioning pipeline's data structure for consumed materials.
In the end this enables the customer to integrate the child parts into the SingleLevelBomAsBuilt aspect.

Unique ID Push Process

Connect to Child

How the actual process is triggered is application specific. It is recommended to trigger the push of "connect-to-child" towards the supplier earliest after the singleLevelBom aspect (AsBuilt oder AsPlanned) has been created, since at that point all relevant information is available. It is also possible to collect "connect-to-child" notification content at customer side and send this in a list to the supplier, e.g. once a day or once a week.

The Unique ID push is initiated by the customer (acting as sender) towards their supplier (acting as receiver). The body information comes from the corresponding singleLevelBom aspect.

Upon receipt of the message, the supplier needs to update the corresponding singleLevelUsageAspect(s) at his side. All information required can be taken from the body in the notification.

Schema of Unique ID Push Notifications

The Unique ID Push notifications have a standardized format. Schemas of these notifications are described in detail in the Unique ID Push Open API specification. The standardized version of this API is 2.0.0. Version 2.1.0 is not (yet) standardized, but backwards compatible, and extends v2.0.0 with the Connect-to-Child feature.

Connect to Parent

For the context field in the notification header, use the following string for Unique ID Push notifications as described in this KIT: IndustryCore-UniqueIDPush-ConnectToParent:<API version>.
Adding the customer part ID to the notification is optional. The main reason for this is that it cannot be guaranteed that every manufacturer knows the customer part ID for their parts. But, in case the manufacturer knows the customer and the corresponding customer part ID of its part though, it is required to always add the customer part ID to the notification.

Connect to Child

For the context field in the notification header, use the following string for Unique ID Push notifications as described in this KIT: IndustryCore-UniqueIDPush-ConnectToChild:<API version>.

Notification Receiver

Here is a short overview what the receiver has to do when they want to support Unique ID Push notifications. This is an optional feature.

Connect to Parent The receiver in this scenario is the customer of a part.
Connect to Child The receiver in this scenario is the supplier of a part.
The receiver must create a EDC asset in their EDC that works as the endpoint for receiving notifications. Also, access & usage policies as described below must be configured.
The EDC in which the notification EDC asset was created must be registered at the EDC Discovery (so that the sender can find the partner's EDC which should receive notifications)
When the Receiver receives a Unique ID Push notification, it must process this notification after it was received by the EDC (in a Backend Data Service)
How the Receiver processes the notification is up to them, but the following steps are recommended:
- Verify the correctness of the data in the notification (i.e., the receiver is actually the customer of this part).
- Store the notification data for later.
- Connect to Parent Use this data when the digital twin for the part into which the delivered part is built into is created instead of doing a lookup to a supplier's Digital Twin Registry.
- Connect to Child Use this data to update the corresponding singleLevelUsage aspect

EDC Asset

For the EDC asset for receiving Unique ID Push notifications, the following properties must be set:

{
  "@context": {
    "edc": "https://w3id.org/edc/v0.0.1/ns/",
    "cx-common": "https://w3id.org/catenax/ontology/common#",
    "cx-taxo": "https://w3id.org/catenax/taxonomy#",
    "dct": "https://purl.org/dc/terms/"
  },
  "@id": "{{ _.assetId }}",
  "properties": {
    "dct:type": { "@id": "cx-taxo:{{ _.notificationType }}" },
    "cx-common:version": "2.1"
  }
}

Properties https://purl.org/dc/terms/type and https://w3id.org/catenax/ontology/common#version are used to classify the asset and are explained in the Digital Twin KIT in more detail.

For {{ _.notificationType }}, use

UniqueIdPushConnectToParentNotification for the Connect-To-Parent notification asset and
UniqueIdPushConnectToChildNotification for the Connect-To-Child notification asset.

✋ Note that the API version can be different depending on what Unique ID Push API version your company supports.

EDC Policies

Access Policies A data provider can decide on its own what access policies they want to define for their notification asset. Based on the purpose of the asset, all suppliers of the data provider should in general be allowed to send notifications to this asset. Therefore, either a public access policy or a BPN-based access policy (allowing all suppliers) should be used.

Usage Policies In general, a data provider is free to decide which usage policies to define for its assets. For notifications, though, the data provider is actually the receiver of notifications, i.e., the usage policy here has the purpose to define what the data provider does or is allowed to do with the notifications. It's something the sender of the notification has to rely on and accept when sending its notification.

Keep in mind that usage policies currently aren't technically enforced by the EDC or other components.

✋ Usage Policy for Unique ID Push The Unique ID push notification endpoints are protected with a purpose-based usage policy and "cx.core.industrycore:1" as purpose.

Backend Data Service to Process Unique ID Push Notifications

The receiver must setup a backend data service that provides an HTTP Endpoint for notifications. All endpoints are described in detail in the Unique ID Push Open API specification. The standardized version of this API is 2.0.0. Version 2.1.0 is not (yet) standardized, but backwards compatible, and extends v2.0.0 with the Connect-to-Child feature.

Notification Sender

Here is a short overview what the sender has to do when they want to support Unique ID Push notifications. This is an optional feature.

Connect to Parent (Sender = Supplier)

The Sender in this scenario is the manufacturer or supplier of a part.
When a new digital twin for a part was created, the manufacturer is responsible to send a Unique ID Push notification for this twin to the customer of this part.
It is recommended to send this notification as soon as possible, i.e., directly after the digital twin was created.

Connect to Child (Sender = Customer)

The Sender in this scenario is the consumer of the supplied part.
When the supplied part is used in the production or assembly at the customer side, the customer is responsible to send a Unique ID Push notification for the twin of the used part to the supplier of this part. This is known by the customer when the singleLevelBom aspect is created or updated.
This notification can be sent immediately or collected to be sent when convenient, e.g. once a day or once a week, depending on the use case.

Mapping BPN to EDC URL with EDC Discovery API

Connect to Parent The sender must first find the EDC of the customer (receiver) to which the notification should be sent to. For this, the BPN of the customer is required.

Connect to Child After creating the singleLevelBom aspect the sender should already know the BPN of the supplier (receiver).

With this, the EDC Discovery can be used to query for all EDCs of the receiver. After that, the data catalog of each of these EDCs must be queried for the notification EDC asset as described above. If this notification EDC asset is found in one of these EDCs, the notification can be sent.

There should only be one EDC which provides the notification EDC asset for Unique ID Push. If more than one EDC (for the same BPN/partner) are found, this is considered a misconfiguration of the corresponding partner.

NOTICE

This work is licensed under the CC-BY-4.0.

SPDX-License-Identifier: CC-BY-4.0
SPDX-FileCopyrightText: 2023 BASF SE
SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Foerderung der angewandten Forschung e.V. (represented by Fraunhofer ISST & Fraunhofer IML)
SPDX-FileCopyrightText: 2023 German Edge Cloud GmbH & Co. KG
SPDX-FileCopyrightText: 2023 Mercedes Benz AG
SPDX-FileCopyrightText: 2023 Robert Bosch Manufacturing Solutions GmbH
SPDX-FileCopyrightText: 2023 SAP SE
SPDX-FileCopyrightText: 2023 Siemens AG
SPDX-FileCopyrightText: 2023 T-Systems International GmbH
SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG
SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation
Source URL: https://github.com/eclipse-tractusx/eclipse-tractusx.github.io/tree/main/docs-kits/kits/Industry%20Core%20Kit (latest version)

Register Digital Twins​

Regulatory Compliance and Security​

Unique ID for Parts​

Conventions for Creating Digital Twins​

Property specificAssetIds​

Submodel Descriptors​

Submodel Descriptors​

Option 1: Same Connector Asset Structure as in Release 3.1​

Option 2: Connector Asset Structure on Catalog Part Level​

Data Consumption with AAS Submodel Descriptor Endpoints​

Lookup in the Digital Twin Registry​

Lookup up a Digital Twin with Local IDs​

Unique ID Push​

Query a Digital Twin Registry to find the digital twin for this built-in part​

Publish Traceability Data Offers in the Connector​

Data Provider Tasks​

Unique ID Push​

Connect to Parent​

Connect to Child​

Prerequisites and Constraints​

Unique ID Push Process Overview​

Connect to Parent​

Connect to Child​

Schema of Unique ID Push Notifications​

Connect to Parent​

Connect to Child​

Notification Receiver​

EDC Asset​

EDC Policies​

Backend Data Service to Process Unique ID Push Notifications​

Notification Sender​

Connect to Parent (Sender = Supplier)​

Connect to Child (Sender = Customer)​

Mapping BPN to EDC URL with EDC Discovery API​

NOTICE​

Register Digital Twins

Regulatory Compliance and Security

Unique ID for Parts

Conventions for Creating Digital Twins

Property specificAssetIds

Submodel Descriptors

Submodel Descriptors

Option 1: Same Connector Asset Structure as in Release 3.1

Option 2: Connector Asset Structure on Catalog Part Level

Data Consumption with AAS Submodel Descriptor Endpoints

Lookup in the Digital Twin Registry

Lookup up a Digital Twin with Local IDs

Unique ID Push

Query a Digital Twin Registry to find the digital twin for this built-in part

Publish Traceability Data Offers in the Connector

Data Provider Tasks

Unique ID Push

Connect to Parent

Connect to Child

Prerequisites and Constraints

Unique ID Push Process Overview

Connect to Parent

Connect to Child

Schema of Unique ID Push Notifications

Connect to Parent

Connect to Child

Notification Receiver

EDC Asset

EDC Policies

Backend Data Service to Process Unique ID Push Notifications

Notification Sender

Connect to Parent (Sender = Supplier)

Connect to Child (Sender = Customer)

Mapping BPN to EDC URL with EDC Discovery API

NOTICE